<HTML><HEAD><TITLE>local +SpecList</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Modules</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>local +SpecList</H1>
Declare all items specified by SpecList as local to the caller module.
<DL>
<DT><EM>SpecList</EM></DT>
<DD>One or a comma-separated sequence of valid local specifications
</DD>
</DL>
<H2>Description</H2>

    This declaration is used to declare the visibility of procedures
    and other items as local to the caller module.  SpecList is a
    comma-separated sequence of one or more items of the following form:
<DL>
<DT><STRONG>Name/Arity</STRONG><DD>
        procedure specification

<DT><STRONG>domain(Spec)</STRONG><DD>
	domain declaration

<DT><STRONG>struct(Prototype)</STRONG><DD>
	structure declaration

<DT><STRONG>variable(Name)</STRONG><DD>
	non-logical variable declaration

<DT><STRONG>variable(Name,InitialValue)</STRONG><DD>
	non-logical variable declaration with initial value

<DT><STRONG>reference(Name)</STRONG><DD>
	reference declaration

<DT><STRONG>reference(Name,InitialValue)</STRONG><DD>
	reference declaration with initial value (ground term)

<DT><STRONG>array(Name)</STRONG><DD>
	untyped non-logical array declaration

<DT><STRONG>array(Name,Type)</STRONG><DD>
	typed non-logical array declaration

<DT><STRONG>record(Name)</STRONG><DD>
	record key declaration

<DT><STRONG>shelf(Name,InitialValue)</STRONG><DD>
	shelf name declaration with initial value

<DT><STRONG>store(Name)</STRONG><DD>
	store name declaration

<DT><STRONG>op(Prec,Assoc,Name)</STRONG><DD>
	operator declaration

<DT><STRONG>chtab(Char,Class)</STRONG><DD>
	character class declaration

<DT><STRONG>syntax_option(Option)</STRONG><DD>
	syntax option setting

<DT><STRONG>macro(Functor,Transformation,Options)</STRONG><DD>
	macro (input transformation) declaration

<DT><STRONG>portray(Functor,Transformation,Options)</STRONG><DD>
	portray (output transformation) declaration

<DT><STRONG>initialization(Goal)</STRONG><DD>
	goal to be executed just after the module has been loaded

<DT><STRONG>finalization(Goal)</STRONG><DD>
	goal to be executed just before the module is erased (whether
	explicitly, or implicitly during recompilation or exiting ECLiPSe)
</DL>

   The effect of the local-declaration is that the declared items are
   only visible inside the module where they have been declared.
<P>
   <BIG>Local Procedures</BIG>
<P>
   For procedures, the local-declaration is normally redundant because
   local visibility is the default.  However, it might be necessary to
   explicitly declare a procedure as local to resolve a name conflict
   when an imported module exports a procedure of the same name.
<P>
   Local declarations should be placed at the beginning of a module text.
   They must occur before the first reference to the declared prodecure:
<P>
   A procedure can have four kinds of visibility in a given module:
   local, exported, imported or reexported.  A local-declaration is
   silently ignored if the procedure has already been exported before.
   If a procedure of the given name has already been imported or
   reexported, the local-declaration raises an error 94.
   If there is one or more imported modules which export a procedure of
   the same name, these all get hidden silently by the local declaration.
<P>
   A local procedure can only be called from within the module where it is
   defined, even when explicit module qualification via :/2 is used.
<P>
   <BIG>Local Initialization and Finalization</BIG>
<P>
   The local initialization declaration is used to specify an initialization
   goal. All initialization goals which occur within a compilation unit
   (file or module), will be executed just after this compilation unit
   has been loaded by the system.
<P>
   A finalization goal will be executed just before the module containing
   the declaration gets erased. This can happen either explicitly through
   erase_module/1, or implicitly when the module gets recompiled or when
   ECLiPSe exits. Finalisation goals should not do any I/O because in the
   case of an embedded ECLiPSe, I/O may no longer be available at
   finalisation time.
<P>
   <BIG>Other Local Items</BIG>
<P>
   All other local declarations also have an effect only in the module
   where they occur.  Some of them have corresponding export-variants.
<P>
   <BIG>Further Hints</BIG>
<P>
   The local/1 primitive can not only occur as a directive but can also
   be called at runtime.
<P>
   Duplicate local declarations are accepted silently.

<H3>Modes and Determinism</H3><UL>
<LI>local(++) is det
</UL>
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>SpecList is not instantiated.
<DT><EM>(5) type error </EM>
<DD>SpecList is instantiated, but not to a sequence of valid local specifications.
<DT><EM>(94) trying to redefine an existing imported procedure </EM>
<DD>SpecList is already imported.
</DL>
<H2>Examples</H2>
<PRE>
% Normally, local declarations for predicates are redundant:
  :- module(m).

  :- local p/1.         % can be omitted since the default is local
  p(99).


% Redefining a built-in predicate:

    :- module(m)
    :- local writeln/1.   % stop writeln/1 from being imported

    main :-
       writeln(hello).    % local-declaration must be before this use!

    writeln(X) :-         % the local version
       printf("I don't like the normal writeln/1 predicate: %w%n",[X]).


% Redefining an imported predicate:

    :- module(m)
    :- lib(lists).        % module 'lists' defines a predicate subtract/3
    :- local subtract/3.  % stop subtract/3 being imported from 'lists'

    decr(N, N1) :-
       subtract(N,1,N1).  % local-declaration must be before this use!

    subtract(X,Y,Z) :-    % the local version of subtract/3
       Z is X-Y.


% Other local declarations:

   :- local
   	op(500, xfx, before),
	struct(book(author,title,publisher)).

   :- local initialization(writeln("I am being initialized!")).


% Error cases:

  :- local P.                           (Error 4).
  :- local p/a.                         (Error 5).
  :- (import p/0 from m), local(p/0)    (Error 94).
</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/modules/export-1.html">export / 1</A>, <A HREF="../../kernel/modules/reexport-1.html">reexport / 1</A>, <A HREF="../../kernel/modules/import-1.html">import / 1</A>, <A HREF="../../kernel/modules/module-1.html">module / 1</A>, <A HREF="../../kernel/storage/array-1.html">array / 1</A>, <A HREF="../../kernel/storage/array-2.html">array / 2</A>, <A HREF="../../kernel/termcomp/domain-1.html">domain / 1</A>, <A HREF="../../kernel/syntax/macro-3.html">macro / 3</A>, <A HREF="../../kernel/syntax/op-3.html">op / 3</A>, <A HREF="../../kernel/syntax/portray-3.html">portray / 3</A>, <A HREF="../../kernel/storage/reference-1.html">reference / 1</A>, <A HREF="../../kernel/storage/reference-2.html">reference / 2</A>, <A HREF="../../kernel/env/set_flag-2.html">set_flag / 2</A>, <A HREF="../../kernel/storage/store-1.html">store / 1</A>, <A HREF="../../kernel/syntax/struct-1.html">struct / 1</A>, <A HREF="../../kernel/storage/variable-1.html">variable / 1</A>, <A HREF="../../kernel/storage/variable-2.html">variable / 2</A>
</BODY></HTML>
